前一篇我們了解了整個專案所使用的 Python 開發工具。

本文將帶領你一步步完成，有關範例專案的環境設定：從安裝 Python、Poetry、clone 專案至本地、建立 Python 虛擬環境，到成功啟動 Django。

即使你從未接觸過這些工具，按著本文的指南，應該也能順利完成環境設定並運行。

值得一提的是，我已經使用 Mac 很長一段時間，對 Windows 環境不甚熟悉，但我會盡可能提供相關的替代方案或指引。

好，我們開始吧！

一、安裝 Python 3.12

因為不是每個人的環境都方便安裝 pyenv（尤其它不支援 Windows）， 這裡只講沒有 pyenv 的替代方案。

如果想透過 pyenv 安裝 Python， 可以參考上一篇提到的教學文章。

我們直接從 Python 官方網站下載並安裝 Python 3.12。

Windows 使用者

1. 前往 Python 官方的下載頁面，下載 Python 3.12 的 Windows 安裝程式。
2. 執行下載的安裝檔，記得勾選「Add Python 3.12 to PATH」選項。
3. 完成安裝後，開啟命令提示字元並輸入python --version來確認是否安裝成功。

macOS 使用者

對於 macOS 使用者，我們有幾種安裝 Python 3.12 的方法：

1. 使用 pyenv：這是我個人推薦的方式。
2. 一樣使用官方安裝程式：前往 Python 官方網站下載 macOS 版本的安裝程式，並按照指示完成安裝。
3. 使用 Homebrew：如果你已經安裝了 Homebrew，可以在終端中執行 brew install python@3.12 來安裝 Python 3.12。

安裝完成後，在命令列中輸入 python3 --version 來確認安裝是否成功。

不管用哪一種方式安裝，請務必透過上述指令確認 Python 版本正確。只要是 3.12.x 即可。

❯ python3 --version
Python 3.12.5

二、安裝與設定 Poetry

專案中的所有 Python 套件都由 Poetry 管理，首先要安裝 Poetry。可以直接通過官方指令安裝：（以下指令適用 macOS 和 Linux 用戶）

curl -sSL <https://install.python-poetry.org> | python3 -

安裝完成後，將 Poetry 執行檔路徑，新增到系統的 PATH 中：（Zsh 用戶）

echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc

Bash 用戶：

echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc

檢查是否安裝成功：

❯ poetry --version
Poetry (version 1.4.0)

Windows 安裝與設定 Poetry

Windows 用戶可參考 JetBrains 的 Poetry 設定教學，我覺得寫得很清楚。

修改 Poetry config，改用.venv虛擬環境

預設為false，Poetry 會在獨立目錄下建立虛擬環境，而名稱很冗長！

改成true以後，則直接在專案根目錄下建立虛擬環境，且名稱固定為.venv。

poetry config virtualenvs.in-project true

把虛擬環境放在專案中，這是我個人更偏好的做法。

不使用 Poetry 的方案

專案中準備了一份 requirements.txt 給習慣用 pip 的讀者。省去安裝與設定 Poetry 的麻煩。

三、從 GitHub 下載專案、建立虛擬環境

接下來是專案本身的設定。

一、Clone 專案

這是專案連結。使用git clone指令：

git clone https://github.com/kyomind/Django-Ninja-Tutorial.git
# 或
git clone git@github.com:kyomind/Django-Ninja-Tutorial.git

二、建立虛擬環境並安裝套件

進入專案目錄，使用 Poetry 建立虛擬環境：

poetry env use 3.12

此時在專案根目錄應該會建立一個.venv資料夾，即專案的虛擬環境，目前是空的。

使用poetry shell啟動虛擬環境。

透過poetry install安裝套件：Poetry 會根據pyproject.toml和poetry.lock內容，自動下載並安裝專案需要的所有套件。

pip 使用者

pip 用戶可以透過以下步驟建立虛擬環境：（全程在專案根目錄下進行）

1. 使用 Python 內建的 venv 模組建立虛擬環境：python -m venv .venv
2. 啟動虛擬環境：
   • Windows: .venv\Scripts\activate
   • macOS/Linux: source .venv/bin/activate
3. 安裝套件：pip install -r requirements.txt

四、初始化 pre-commit

建立虛擬環境並使用poetry install後，pre-commit 套件已被安裝到虛擬環境中。

如你所見，專案中有一個.pre-commit-config.yaml檔。這個檔案定義了每次提交前要執行的檢查項目（Git Hooks）。

我們只需要透過下列指令，安裝 Git Hooks：

pre-commit install

這個指令會在專案的 Git 目錄中建立 Git Hooks，每個專案只要執行一次即可。

五、安裝 VS Code 套件

如果你的 IDE 是 VS Code，我強烈建議安裝 Ruff 和 Mypy 這兩個 VS Code 套件。讓你可以在第一時間知曉目前的程式碼狀態（是否有問題）。

兩者在安裝後，原則上都無須設定，因為專案內已經有了相關的設定檔：

1. Ruff：pyproject.toml
2. Mypy：mypy.ini（在專案最新進度中已併入pyproject.toml）

此外，它們都是 CLI 工具，所以你也可以手動執行它們，比如執行 Ruff 檢查：

ruff check
ruff format

或執行 Mypy 檢查：

mypy .

但還是 VS Code 套件最方便。

六、啟動 Django 專案

我們已經完成了所有必要的工具設定，接下來就可以啟動 Django 伺服器了。

一、進行資料庫遷移

這是一開始一定要的步驟：

python manage.py migrate

事實上，專案也準備了 Makefile，所以你也可以透過以下指令執行遷移：

make migrate

有關 Makefile 的介紹與教學，可以參考小克這篇〈寫 Web 也可以用 Makefile：好好管理你的環境流程〉。

二、啟動開發伺服器

執行以下命令來啟動 Django 開發伺服器：

python manage.py runserver
# 或
make run

接著，打開瀏覽器並訪問 http://127.0.0.1:8000/，你應該可以看到 Django 預設的歡迎頁面，表示專案成功啟動！

小結

通過上述步驟，你已經成功完成了專案的開發環境設定，並啟動了範例 Django 專案。

如果在設定過程中遇到問題，可查閱工具的官方文件或參考我的部落格教學，這些資源能幫助你解決常見問題，或進一步理解它們的功能。

專案分支與 PR

在專案的開發過程中，我們會使用 Git 分支和 GitHub 的 PR（Pull requests）來管理不同章節的範例程式碼改動。

這樣可以保持學習脈絡清晰有條理，避免因不同功能的程式碼混在一起而影響理解。

需要注意的是，不是每一篇文章都有自己的分支與 PR，因為有些篇章只涉及概念說明而沒有程式碼改動。

CodeGPT 推薦

此外，本專案幾乎所有的 commit 訊息，都是透過吳大開發的 CodeGPT 加上 GPT-4o mini API 自動生成。

畢竟，即使只是範例專案，要思考每一個 commit 訊息的內容也是不輕鬆。有了這樣的自動化工具，真的方便很多！而且風格一致性高，很適合偏執狂如我☺️

關於 CodeGPT，除了 GitHub 頁面介紹，還可以參考吳大的這篇〈生成式 AI CodeGPT 開發經驗談 - 台北 ModernWeb〉，內有投影片分享。

使用教學則可參考保哥的〈介紹好用工具：CodeGPT (使用 GPT 自動化產生 Git 的 Commit Log 訊息)〉。

現在，一切準備就緒，讓我們正式進入 Django Ninja 的世界。

本文同步發表於我的部落格——Code and Me